feat: implement the case matrix — records, reachability, methods, and the mark's exit - #13

…et (#28)

Asked whether `@experimental` itself has settled, the churn says yes — `src/mark.jl` has not been
touched since #13, across the fourteen commits since. So the question was put to a sweep of 25
definition forms instead, and the sweep found one hole, in the class this package exists to close.

    @experimental "kernel unverified" @inline f(x) = x     # mark outside
    @inline @experimental "kernel unverified" g(x) = x     # mark inside

    entered(M)  →  [:g]

Both are marked. Both **register a probe**, so both count as observable marked definitions. Only
one can ever be entered. With the mark outside, `entered` said "not entered" no matter what ran,
`@entered` and `record` reported a clean run through unvalidated code, and `unverified` reported
the definition forever.

`_subject` was right: `@inline` and its five neighbours are in `_ANNOTATING_MACROS`, the wrapper is
rebuilt around the definition, and `instrumentable` is passed through — with a comment saying "an
`@inline` marked kernel is exactly the kind that has to be observable". `_instrument`, in the other
file, began `(def.head === :function || def.head === :(=)) || return nothing` and handed back
`nothing` for the `:macrocall` it was given. Two halves of one feature written to different
assumptions. It now recurses through the wrapper and rebuilds it around the instrumented body.

**The docstring documented the defect.** Its table read "`Base.@kwdef`, `@inline`, `@noinline` and
the other pass-through macros | no", which is what the code did, not what the code was for. The row
is now split: the six annotating macros are observed; `@generated` (its body returns an expression)
and `Base.@kwdef` (it wraps a struct) are not, and each says why.

**The test was named for the claim and asserted something weaker.** `@testset "@inline and the mark
compose in both orders"` asserted `Set([:f, :g]) == names marked` — satisfied by a mark that can
never fire. It now asserts the observation, and a second testset pins the split that a careless fix
would break: instrumenting every macrocall would put a probe inside `@generated`'s returned
expression.

Three refusals had no test at all — measured by grepping `test/` for their message text and finding
zero hits: a wrapping macro this cannot read, a `begin` block with two definitions in it, and a bare
qualified name. Each is now pinned on the part that makes it actionable — the name of the macro it
could not read, the word `block`, `Sub.g` and the form that would work — rather than on the fact
that something was thrown.

One incidental find while pinning them: a macro that throws while expanding a `module` body run
through `include_string` comes back wrapped in `LoadError` **twice**, so the usual single `.error`
leaves a `LoadError` that reads exactly like the failure it hides.

186 behaviours, 1210 assertions, green.

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

* docs: every block that shows output now produces it

Measured: 33 fenced ```julia blocks across `docs/src`, of which **12 displayed output that had
been typed by hand**. Those 12 are the ones that can be wrong, and three of them were.

All 12 now execute — `@setup` fixtures plus `@repl`/`@example` — and the build fails if their
output stops matching. Typed-output blocks remaining: 0.

What executing them found:

  * `@experimental "why" Base.sum(x::Int) = x` is documented as REFUSED. It is accepted: method
    marks on another module's generic landed in #13, and the page was never revisited. The
    refusal example is now one that is still refused (a bare `Sub.g`), rendered from the real
    message, and the accepted-forms list gains the foreign-method case with the note that it is
    reported by `contributed_methods` rather than by the name audit.
  * `mark(Archeion, :ingest)` was shown without its `signature:` line, which the real display has.
  * The `entered()` transcript carried a reason for not being executable — "Documenter evaluates
    doctests in a sandbox whose module does not print as `Main`". Measured: an `@repl` block shows
    `Main.MyModel.energy`, so the reason no longer holds. It is now `entered(MyModel)`, asked about
    a module because the process-wide answer includes every fixture the documentation built.

Two blocks show what a documentation build genuinely gets rather than what a user would, and say
so: `record`'s timings are `missing` because a docs build does not load `Profile`, and
`coverage(...)` is `missing` because it has no `--code-coverage` counters. Both are the documented
contract, now demonstrated instead of described.

`record(; paths = false)` on the observing page: a captured path is the whole call stack, and in a
docs build that starts at `_start` and runs through `makedocs`.

1253 assertions, green; docs build clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs: the @entered report was rendered away by Documenter, not lost by the macro

The walkthrough showed

    value = ExperimentalAPI.@entered Ising.report(βs)
    -1.8886

— the value, and nothing else. The report is the whole of what `@entered` is for.

Not the macro. `IOCapture`, which is what Documenter captures with, sees it:

    captured output = "┌ @entered S.f(1.0)   at cap.jl:8\n│   Main.S.f  ×1 — r\n└ 0 of 1 …\n"
    value           = 2.0

Measured on a minimal Documenter site, with the control that settles it:

    block                                   value    rendered
    @entered S.f(1.0)                       2.0      2.0
    println("plain println"); 99            99       99          ← the println is lost too
    println("plain println only")           nothing  plain println only

An `@example` renders the block's value when it has one and its captured output only when the
value is `nothing`. A plain `println` followed by a non-`nothing` value loses its line exactly the
same way, which is what says this is Documenter and not us.

So the walkthrough uses `@entered <io> expr` and prints the buffer — the form `observing.md`
already used for the same reason — and the page now says why, with the control, and adds that a
reader at a terminal writes the plain form. All three `@entered` blocks in the built docs now
carry their report.

1250 assertions, green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>